Review — PR #804 (feat(harness): unify project agents and restore map navigation)

1. GET /api/state can spawn sessions in a loop when a bootstrap session dies early

listWorkflows → annotateStudioSelections → convergeReconciledProjectLifecycle →
ensureProjectFirstSession (src/server/index.ts:3432, :3115, :2845-ish). That chain runs on
every GET /api/state and GET /api/workflows, so two read-only endpoints now create PTY sessions
as a side effect.

needsProjectSession (src/core/planner-greeting.ts:814) treats a claimed intent as replaceable
whenever the target session is exited with agentSessionId === null, and explicitly clears the
in-memory provisionalProjectClaims guard in that case. There is no bound on replacements —
MAX_RETRIES only bounds prompt attempts inside one claimed session (:1539).

Failure scenario: a new project's Plan Agents session spawns, but the agent binary exits before
the SessionStart hook posts an agentSessionId (unauthenticated claude, crash on startup, bad
config — AdapterNotFoundError/ExternalHarnessError are caught at :2870, this case is not).
The session exits with agentSessionId: null. The next /api/state read returns needsProjectSession = true and spawns a replacement; that create broadcasts an event, the SPA refetches state, and the
cycle repeats. The user sees an ever-growing tab strip of dead sessions and repeated process spawns
until they remove the project.

Needs either a durable attempt counter on the intent (mirroring retryCount) or a rule that a
replacement is only minted from an explicit lifecycle boundary, not from a read path.

2. Breaking public-type change shipped as minor with no migration note

HarnessSession is public (src/index.ts:6 re-exports all of shared/types.ts).
agentMapIdentity narrows from PlanningSessionIdentity (union carrying role and assignment)
to ProjectAgentSession ({projectId, userId, sessionId}), planning is deprecated and deleted
from sessions.json on first boot (src/core/session-manager.ts:901), and
PlannerSessionMetadataResponse.metadata changes shape and gains | null. A consumer reading
session.agentMapIdentity.role stops compiling; one reading it at runtime gets undefined.

.changeset/unified-project-agents.md is one sentence at minor with no Breaking heading and
no migration note. Per the repo's changeset policy this needs the breaking callout naming the
dropped role/assignment fields, the planning removal, and the deprecated planner routes. The
changeset is the one surface that can't be edited after publish.

Also missing from the docs: CreateSessionRequest.initialUserInputPending is a new public request
field (src/shared/types.ts:1108, validated in rest.ts:97) with no README coverage.

3. onRecentDirAdded fires for every recent dir, not just new ones

rest.ts:423 iterates the whole submitted recentDirs array; the option's own JSDoc two hunks
earlier says "Called only for roots newly added to the user's durable project list." The SPA
PATCHes the full capped list on every project open (web/src/lib/use-harness-state.ts:1503,
cap 8), so one click runs up to 8 sequential initializeOpenedProject passes. Each does a full
studioWorkspaceScopeCatalog.list() (stat every candidate root plus identity resolution for every
durable project) and a catalog reconcile, all serialized on projectScopeResolutionQueue — the same
queue that gates resolveAgentMapIdentity, so session creation stalls behind it. The PATCH response
is held until all of them finish.

Worse, the settings write has already committed before the loop. Any error that escapes
ensureProjectFirstSession — e.g. SpawnTargetError on Windows, which is not in the caught set at
src/server/index.ts:2870 — turns a durable, successful settings save into a 500.

The inline comment justifies the fan-out as retry convergence, but three idempotent convergence
points already exist (boot outbox recovery, convergeReconciledProjectLifecycle, onRootBound).
Filter to newly-added roots, and wrap the callback so lifecycle failure can't fail the settings
response.

Verdict: Request changes — finding 1 is a user-visible session-spawn loop reachable from a
read-only endpoint; findings 2 and 3 are a mislabeled public-API break and a hot-path contract
violation. The confidentiality/public-copy surfaces (changeset text, README, new prose) are clean:
no non-Sapiom company names, business arrangements, or internal hostnames. No dependency,
files/exports, or tarball changes.

Follow-up review — PR #804 (delta b931e798 → 036a73c6)

Earlier findings

1. Session-spawn loop from GET /api/state — fixed. needsProjectSession
   (src/core/planner-greeting.ts:1391) now only returns true when the target session row is
   absent and the provisional claim has been released, so an exited session with
   agentSessionId: null can no longer mint an unbounded chain of replacements.
2. Breaking public-type change shipped as a bare minor — fixed.
   .changeset/unified-project-agents.md now carries the Breaking for embedders callout,
   names the dropped agentMapIdentity.role/.assignment, the planning → projectBootstrap
   migration and the metadata: null alias shape, and gives a migration paragraph;
   initialUserInputPending is documented in the harness README.
3. onRecentDirAdded fan-out — fixed. rest.ts:432 diffs the committed list against the
   prior one and only calls back for newly-added roots, and each call is wrapped so a lifecycle
   failure can no longer turn a durable settings write into a 500. Both sides of the diff come
   from sanitizeRecentDirs, so the comparison is normalized-vs-normalized.

New finding

SessionInputIsolationError is unreachable by any HTTP status mapping — a fenced composer
returns 500 instead of a retryable 409. The new error (src/core/session-manager.ts:93,
thrown at :1639, :1670, :1762) carries code: "SESSION_INPUT_ISOLATION_REQUIRED", but
neither rest.ts:948 (POST /api/sessions/:id/input) nor sendProjectSessionError
(agent-map.ts:99) lists it, so it falls through to the generic handler. Failure scenario: a
pty.write fails mid-line (EPIPE/EAGAIN on a dying pty), markComposerUnsafe fences the handle,
and the user's next send returns an opaque 500 — the SPA has no way to distinguish "reset and
retry" from a server fault, and the sibling case (SessionBackgroundInputPreemptedError) was
explicitly added to the 409 set in this same commit.

Corrections to the earlier round

None.

Verdict: Comment — all three earlier findings are resolved; the one new finding is a missing
error-status mapping, not a data-loss or leak. Delta prose (changeset, README, comments) is clean:
no non-Sapiom company names, internal hosts, or ticket links in shipped text. No dependency,
files, or exports changes.

/review

Follow-up review — PR #804 (delta 036a73c6 → 5d00c559)

The push resolves the only open finding, and I found nothing new.

• Round 2's finding — fixed. SessionInputIsolationError is now in the 409 set on both
  POST /api/sessions/:id/input (src/server/rest.ts:952) and sendProjectSessionError
  (src/server/agent-map.ts:105), with a test per route asserting the
  SESSION_INPUT_ISOLATION_REQUIRED body. The remaining throw site is write()
  (session-manager.ts:1670), which is the terminal WS path and already closes with the
  dedicated input-failure code (terminal-ws.ts:85-95); the bootstrap coordinator path
  (:1762) calls onNotSubmitted first, so planner-greeting.ts:3408 classifies it as a
  retryable pre-Enter failure. All three sites are covered.
• No new findings. Delta is 4 lines of error mapping plus two tests; no prose, dependency,
  files/exports, or public-type changes. Test-only strings are provider-neutral with no
  company names or internal references.
• Corrections to earlier rounds: none.

Verdict: Approve.

Superseded by the maintainer-authorized 15-part Agent Map review stack. This PR is closed without merging; its branch and review history remain preserved.

Replacement increments:

• Part 01/15: refactor(harness): share project roots [Agent Map 01/15] #819 — refactor(harness): share project roots
• Part 02/15: feat(harness): unify project sessions [Agent Map 02/15] #820 — feat(harness): unify project sessions
• Part 03/15: feat(harness): restore project navigation [Agent Map 03/15] #822 — feat(harness): restore project navigation
• Part 04/15: fix(harness): track session input delivery [Agent Map 04/15] #823 — fix(harness): track session input delivery
• Part 05/15: feat(harness): persist bootstrap claims [Agent Map 05/15] #824 — feat(harness): persist bootstrap claims
• Part 06/15: feat(harness): coordinate project bootstrap [Agent Map 06/15] #825 — feat(harness): coordinate project bootstrap
• Part 07/15: feat(harness): activate ordinary bootstrap [Agent Map 07/15] #826 — feat(harness): activate ordinary bootstrap

The complete testing branch remains fix/studio-onboarding-followups. Full stack: #819 through #834. Final hosted-review corrections and Mac journey validation are continuing on those same replacement PRs.